/*
 * The contents of this file are subject to the terms of the Common Development and
 * Distribution License (the License). You may not use this file except in compliance with the
 * License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
 * specific language governing permission and limitations under the License.
 *
 * When distributing Covered Software, include this CDDL Header Notice in each file and include
 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
 * Header, with the fields enclosed by brackets [] replaced by your own identifying
 * information: "Portions Copyrighted [year] [name of copyright owner]".
 *
 * Copyright 2013-2015 ForgeRock AS.
 */

package org.forgerock.openam.sts.soap.token.config;

import org.apache.cxf.sts.token.canceller.TokenCanceller;
import org.apache.cxf.sts.token.provider.TokenProvider;
import org.apache.cxf.sts.token.validator.TokenValidator;
import org.forgerock.openam.sts.STSInitializationException;
import org.forgerock.openam.sts.TokenType;
import org.forgerock.openam.sts.token.validator.ValidationInvocationContext;

/**
 * Interface consumed by the Token*OperationProvider classes to obtain instances of the TokenValidator, TokenProvider,
 * or TokenCanceller classes for the various token types validated or generated by the sts.
 */
public interface TokenOperationFactory {
    /**
     * Called to obtain the set of TokenValidator instances to perform pure token validation in the context of
     * enforcing SecurityPolicy bindings and validating delegated tokens (ActAs/OnBehalfOf case).
     * @param validatedTokenType the type of token to be validated
     * @param validationInvocationContext the context of this validation (SecurityPolicy binding enforcement, delegated token
     *                                    context).
     * @param invalidateAMSession whether the OpenAM session resulting from successful token validation should be invalidated
     *                            at the completion of the operation
     * @return A TokenValidator implementation which can validate the specified token type
     * @throws STSInitializationException if the TokenValidator cannot be created
     */
    TokenValidator getTokenValidator(TokenType validatedTokenType, ValidationInvocationContext validationInvocationContext,
                                     boolean invalidateAMSession) throws STSInitializationException;

    /**
     * Called to obtain the set of of TokenProvider instances to satisfy the issue operation.
     * @param issuedTokenType The type of token to be issued
     * @return the TokenProvider which can issue the specified type
     * @throws STSInitializationException if the TokenProvider cannot be created.
     */
    TokenProvider getTokenProvider(TokenType issuedTokenType) throws STSInitializationException;

    /**
     * Returns a TokenValidator which will validate tokens issued by the STS. Note that in the 13 release, this will
     * only involve checking whether the token has been persisted in the CTS. It will not involve the consumption of
     * an authN module. Only TokenValidators will be created for the TokenTypes corresponding to STS-issued tokens - i.e.
     * OIDC and SAML2 tokens.
     * @param validatedTokenType the type of token to be validated.
     * @return a TokenValidator implementation which simply consults the TokenService to determine whether the token
     * has been persisted in the CTS.
     * @throws STSInitializationException if the TokenValidator cannot be created.
     */
    TokenValidator getSimpleTokenValidator(TokenType validatedTokenType) throws STSInitializationException;

    /**
     * Returns a TokenCanceller instance which will cancel an STS-issued token. This will simply involve invoking the
     * TokenService to remove the token from the CTS. Only TokenCancellers will be created for the TokenTypes
     * corresponding to STS-issued tokens - i.e. OIDC and SAML2 tokens.
     * @param cancelledTokenType the type of to-be-cancelled token
     * @return A TokenCanceller instance which can handle the cancellation of the specified TokenType
     * @throws STSInitializationException if the TokenCanceller cannot be created
     */
    TokenCanceller getTokenCanceller(TokenType cancelledTokenType) throws STSInitializationException;
}
